fix(spec): reconcile the api and platform skill indexes with what their bodies teach - #15424

Fixes #15361
Fixes #15264

Executes maintainer decision batch #36 (1 A · 2 A) and, on the patch round,
maintainer decision batch #39 (ruling D). One rule throughout — the index
advertises what the SKILL.md teaches — applied in three directions: drop a
pointer the body never teaches, add a pointer the body teaches, and constrain
the transitive closure to the members the body names.

What changed

The map spells the added entry 'stack.zod.ts' with no directory segment: the generator resolves every core entry with path.resolve(SPEC_SRC, rel) against packages/spec/src, so a root-level file is spelled bare, as kernel/... ones carry their directory.

The item-2 fork — resolved by ruling D

The fork this PR raised for the approvers (one core pointer publishing 46 further
transitive ones) was ruled in decision batch #39: declare
TRANSITIVE_ALLOWLIST['objectstack-platform'], populated by a mechanical census
and nothing else, then regenerate. That is what this round does.

The rule, and nothing else. A member of objectstack-platform's import
closure stays only if skills/objectstack-platform/SKILL.md names at least
one of that module's exported names, as an exact word-bounded identifier
(backticked or bare). No judgement rows, no hand-picked keeps or drops.

Where the entry lives. The ruling names
packages/spec/scripts/build-skill-references.ts. TRANSITIVE_ALLOWLIST is not
declared there — it is declared in packages/spec/scripts/lib/skill-map-guards.ts
and imported by the generator, next to checkTransitiveAllowlist, the guard that
constrains it. The entry was therefore added at that declaration; the ruling's
substance is unchanged and no second surface was created. This is the one
mechanism assumption in the ruling that did not hold, and it is reported rather
than worked around.

How the census was taken, reproducibly.

• The closure is the generator's own — read from the emitted
  skills/objectstack-platform/references/_index.md at the pre-allowlist head,
  not re-derived by hand: 10 core entries + 73 transitive members.
• Exported names come from each module itself — export const|let|var,
  export function|class|type|interface|enum|namespace, and the names in
  export { … } / export type { … } clauses, alias targets included. 1,244
  exported names were read across the 73 modules. No module in the closure uses
  export *, so nothing is reachable that this extraction cannot see.
  The extraction was cross-checked against the repo's own TypeScript-derived
  packages/spec/export-origins/*.json (which records the declaring file of every
  name each public entry point exports): for all 73 modules, every name that
  artifact attributes to the module is in the extracted set — 0 missing.
• The grep runs over skills/objectstack-platform/SKILL.md only —
  never over references/**, which this generator writes.

Result: 5 of 73 kept. Both shapes the fork named fall out by the rule, not by
hand: automation/state-machine.zod.ts (retired by ADR-0020 as a record-lifecycle
declaration) and data/date-macros.zod.ts (moved to one owning package) are gone
from the index, and neither was touched by hand.

The census

Every closure member, its exported names, the name the SKILL.md carries, and the
verdict. The census read all 1,244 names; the middle column shows the first
six per module so the table stays readable — the cap is a display cap, not a
census cap.

What the constraint costs and saves — measured

skills/objectstack-platform/references/_index.md, by the skills token ratchet's
own counting convention (ceil(utf8 bytes / 4)):

So the patch round is −68 lines / −2,173 tokens against the head the fork
reported, and the index now sits −21 lines / −631 tokens below origin/main —
the ruled stack.zod.ts pointer ships, and the catalogue gets smaller than it was
before the PR. skills/objectstack-api/references/_index.md is untouched by this
round (919 tokens, the batch-#36 value). Whole shipped bundle total: 150,816
tokens.

The ratchet does not object, and says why in its own words — _index.md is
generator-owned, so it is measured, not ratcheted:

✓ check-skills-token-ratchet: skills/objectstack-platform/references/_index.md is 756 tokens — generator-owned (`pnpm --filter @objectstack/spec gen:skill-refs`), measured but not ratcheted.
✓ check-skills-token-ratchet: 36 authored bundle file(s) within their ceilings; 10 generator-owned file(s) measured, not ratcheted.

Exactly the ruled files, and nothing else

Regenerating on the merged tree rewrote one _index.md — the platform one.
The stop condition in the ruling (any other index moving) did not trigger. The
regeneration that preceded the allowlist, run on the merged tree with the ruled
1A/2A content already in place, produced no change at all, so the index diff
below is exactly the allowlist's effect.

Premise re-takes, on this branch's origin/main base

Both premises carried into batch #36 were re-measured before the edit, and both hold.

1 — objectstack-api does not teach the pointer. grep -rn "rest-server\|RestServerConfig\|RestApiConfig\|rest server" skills/objectstack-api/ returns exactly one line, and it is the generated index row this PR removes:

skills/objectstack-api/references/_index.md:17:- `node_modules/@objectstack/spec/src/api/rest-server.zod.ts` — REST API Server Protocol

Over the skill's authored markdown alone (the same grep with --exclude=_index.md, and the skill directory holds only SKILL.md and that index) the count is 0. The wider name sweep — CrudEndpointsConfig, MetadataEndpointsConfig, BatchEndpointsConfig, RouteGenerationConfig — is also 0. The premise holds; the earlier reading's "0 hits" was over authored content, and the one hit here is the artifact being corrected.

2 — objectstack-platform teaches the schema, and nothing advertised it. grep -c "ObjectStackDefinition\|defineStack" skills/objectstack-platform/SKILL.md returns 27. grep -rn "stack.zod" skills/*/references/_index.md packages/spec/scripts/build-skill-references.ts returned no match (exit 1) — the file was in no package's core list and in no index's closure. Both hold.

stack.zod.ts carries no module doc block, so the generator takes its designed fallback and emits the export list rather than refusing: the row reads Exports: DatasourceMappingRuleSchema, ArtifactPackageEntrySchema, AssembledPackageBodySchema, ArtifactPackageSchema, ObjectStackDefinitionSchema. No module header was written into the schema source — that is spec-lane content, out of scope here.

Verification

All of it on the final head 3e9e1eae0, working tree clean. Every exit code was
captured by redirect before any pipe, and each gate is quoted from the verdict
line it prints itself.

The gates the ruling names.

✓ pnpm --filter @objectstack/spec run check:skill-refs   (exit 0)
    ✅ 9 generated files in sync with packages/spec
    objectstack-platform: 10 core + 5 deps
✓ pnpm --filter @objectstack/spec run check:skill-docs   (exit 0)
    ✅ Skill docs in sync
✓ node scripts/check-skills-token-ratchet.mjs            (exit 0)
    ✓ skills/objectstack-platform/references/_index.md is 756 tokens — generator-owned, measured but not ratcheted.
    ✓ 36 authored bundle file(s) within their ceilings; 10 generator-owned file(s) measured, not ratcheted.
✓ node scripts/check-skills-token-ratchet.mjs --self-test (exit 0)

checkTransitiveAllowlist — its verdict, and a probe that it is really the
guard speaking. The guard has no success line to quote: it contributes to the
generator's problems list, and a non-empty list refuses the run in both
modes. A clean gen:skill-refs / check:skill-refs is therefore its verdict, and
on its own that is an argument from silence. So the guard was ablated against the
row this PR adds, with the implementation committed first:

• mutation leg — one extra member added to the new entry, a path the closure
  never reaches. Confirmed on disk before running anything (injected-marker count
  1, not the editor's exit code). Generator exit 1:
  objectstack-platform → shared/does-not-reach-this.zod.ts is in TRANSITIVE_ALLOWLIST but nothing in the package's core closure imports it — this row keeps a pointer that does not exist.
• restore leg — git checkout HEAD -- on the absolute path, then proved: restored
  blob hash 77a5524028a5d7242253c6052b643af076421ea0 equals the HEAD blob,
  git diff HEAD empty, marker count back to 0. The script carried a
  trap … EXIT INT TERM on an absolute path throughout.
• restored leg — the same command, exit 0, ✅ 9 generated files in sync.

No rebuild is involved on either leg: the generator and its guards run from
source through tsx, so there is no dist/ for a stale artifact to hide in.

The generator's own test suite — owed because this diff edits tooling
scripts, over and above any derived family. Run through
scripts/pm/os-verify-lock.sh:

Test Files  4 passed (4)
     Tests  137 passed (137)
os-verify-lock: VERDICT command-exit 0 · held the lock 3s · waited 166s

(skill-map-guards.test.ts, file-description.test.ts, protocol-map.test.ts,
query-pointer-row.test.ts — every test file in the repo naming either script.)

The derived family. node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands
reads the merge base itself rather than a hand-built diff: 4 paths vs merge
base a55efc6c1, 56 commands. All 56 ran.

• 55 exit 0.
• 1 not measured: pnpm check:dual-build-cjs-loads exit 3 — it reads built
  output for the whole workspace and no package is built in this worktree. It says
  so itself: Run pnpm build first. ⛔ This is NOT a pass: nothing was measured.
  Recorded as not measured, not as a pass. This diff ships no package source.

Named verdicts from that run:

✓ check:doc-authoring        — 46 published skill files clean, no internal issue-id references
✓ check:published-files      — 69 publishable package(s) declare a files whitelist
✓ check:nul-bytes            — 7583 text file(s), no raw ASCII control bytes
✓ check:skill-frame-sync     — 2 copies of the decision frame structurally isomorphic
✓ check:skill-compatibility  — 11 SKILL.md reconciled against 79 workspace packages
✓ check:skill-identifier-liveness — 465 citation(s) over 46 published file(s)
✓ check:pm-dispatch-gates    — self-test, 1445 cases pass
✓ check:pm-governed-merges   — self-test; live: the real generator declared 9 output(s)

pnpm lint — the whole repo, not a narrowed scan, through the same lock
wrapper: eslint . --no-inline-config, exit 0, no findings printed.

os-verify-lock: VERDICT command-exit 0 · held the lock 99s (1m39s) · waited 0s

node scripts/pm/check-governed-merges.mjs --test on the four paths returns
GOVERNED, exit 3, and still reports that the generated-surface exception does
not lift either index, because this PR co-edits the generator that exception
would trust:

⛔  GOVERNED — a human merge is the review record for this PR (#9495 regime).
    skills/** ×2 — the published skills catalog
⛔  generated-surface exception (#11705) did NOT lift skills/objectstack-platform/references/_index.md:
    the tree under test modifies the generator this exception trusts

No changeset: this ships no package source. The generator and its guard library are
build scripts and the two indexes are skill markdown, so skip-changeset is the
correct label, and it is on the PR.

This PR stays a draft: governed surface, human merge, two approvers.

Generated by Claude Code